Callback data structure

Every callback procedure gets passed as its last argument a Tcl keyed list of callback data. A keyed list is a list in which each element contains a key and value pair (see TclX for further details). TclX provides comands to access and manipulate keyed lists. This keyed list contains information about the widget that invoked the callback and will always contain at least the following keys:

widget
The name of the widget in which the event occurred.

dialog
The name of the form dialog in which the widget resides.
In addition the callbacks specified with the -callback option will have the following keys:
value
A value corresponding to the contents or the state of the widget. The exact content and meaning of the data for this key depends on the widget and usually corresponds to the data in the widget specific field for the widget.
VtPushButton
The PushButton label string

VtOptionMenu
The name of the widget that activated this callback

VtCheckBox
The list of selected ToggleButtons

VtRadioBox
The name of the widget that activated this callback

VtToggleButton
The name of the selected ToggleButton

VtList
The list of items selected

VtDrawnList
The selected item position

mode
Contains a value indicating what caused the callback to activate. The value for this key is one of the following (see below for individual mode keyedList field values):
done
The user interacted with the widget and explicitly indicated that they have finished interaction. (This usually corresponds to an <Enter> keypress.)

select
The user selected something from the widget. (This usually corresponds to a <Space> press or mouse button click.)

changed
The user interacted with the widget and moved focus away from it. This implicitly indicates that they have finished interaction with the widget. (This usually corresponds to a value change and loss of focus, for example by tabbing or selecting another widget.)

selectSame
The user selected a value that is already selected. This applies only to VtRadiobutton. (This usually corresponds to the user selecting a button that is already selected.)

internalTraverse
This applies only to VtList and VtDrawnList. It occurs when traversing the list using doing up or down arrows.

Additional information depending on the type of widget and callback may be put in the callback data. For example, the callback data for VtList contains the key selectedItemList, that contains a list of items selected.

Note that some additional widget-specific callback keys are provided for backward compatibility with earlier versions of IXI Visual Tcl. They are surrounded by brackets where they appear in the text. Use of these keys is deprecated; they may be withdrawn from a future release of IXI Visual Tcl.

To get access to the data corresponding to a key, use the command keylget. For example, to get access to the button which caused a PushButton callback and the value passed to the callback, the following code might be used: 

   	proc buttonCB {cbs} {
   		set button [keylget cbs widget]
   		set value [keylget cbs value]
   	}

If a callback has additional arguments other than those passed in automatically by the callback structure, declare the arguments first and then declare the callback structure (which is typically referred to as cbs).

That is: 

   	proc buttonCB {arg1 arg2 arg3 cbs} {
   		set button [keylget cbs widget]
   	}
.
.
.
   	VtPushButton $parent.btn  -callback "buttonCB $par1 $par2 $par3"

The following section describes the actions which cause the different mode values.

done
select
change
selectSame
internalTraverse